﻿////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// <copyright>Copyright 2008-2011 Andreas Huber Doenni</copyright>
// Distributed under the GNU General Public License version 2 (GPLv2).
// See accompanying file License.txt or copy at http://phuse.codeplex.com/license.
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

namespace Phuse.Net.Forums
{
    using System;
    using System.Collections.Generic;

    /// <summary>Represents a forum group, the articles of which are cached locally.</summary>
    /// <threadsafety static="true" instance="false"/>
    public interface IGroup : IDeletablePersistentObject
    {
        /// <summary>Gets the host on which this group is hosted.</summary>
        /// <exception cref="InvalidOperationException"><see cref="IDeletablePersistentObject.Delete"/> has been called
        /// on this or the parent <see cref="IHost"/> object.</exception>
        IHost Host
        {
            get;
        }

        /// <summary>Gets the name of the group.</summary>
        string Name
        {
            get;
        }

        /// <summary>Gets or sets the display name of the group.</summary>
        /// <exception cref="InvalidOperationException">Set a value after <see cref="Cache.Dispose"/> has been called
        /// on the parent <see cref="Cache"/> object, or, set a value after
        /// <see cref="IDeletablePersistentObject.Delete"/> has been called on this or the parent <see cref="IHost"/>
        /// object.</exception>
        string DisplayName
        {
            get;
            set;
        }

        /// <summary>Gets or sets the maximum number of new articles for which information is received during each
        /// send/receive operation started with <see cref="Cache.SendReceiveAsync"/>.</summary>
        /// <exception cref="ArgumentOutOfRangeException">Attempted to set a value that is 0 or negative.</exception>
        /// <exception cref="InvalidOperationException">Set a value after <see cref="Cache.Dispose"/> has been called
        /// on the parent <see cref="Cache"/> object, or, set a value after
        /// <see cref="IDeletablePersistentObject.Delete"/> has been called on this or the parent <see cref="IHost"/>
        /// object.</exception>
        /// <remarks>
        /// <para>Only articles where <see cref="IInboundArticle.IsBeingWatched"/> is <c>false</c> count toward this
        /// limit. In any event, the full content is received for all articles that have had their
        /// <see cref="IInboundArticle.IsBeingWatched"/> property set to <c>true</c>.</para>
        /// </remarks>
        int NewInboundArticlesReceiveLimit
        {
            get;
            set;
        }

        /// <summary>Gets the maximum number of articles that are held in the cache.</summary>
        /// <remarks>
        /// <para>This number is enforced in the <see cref="Cache.Compact">Cache.Compact</see> method.</para>
        /// </remarks>
        int CachedInboundArticlesLimit
        {
            get;
        }

        /// <summary>Gets or sets the current filter.</summary>
        /// <exception cref="InvalidOperationException">Set a value after <see cref="Cache.Dispose"/> has been called
        /// on the parent <see cref="Cache"/> object, or, set a value after
        /// <see cref="IDeletablePersistentObject.Delete"/> has been called on this or the parent <see cref="IHost"/>
        /// object.</exception>
        InboundArticleFilter InboundArticleFilter
        {
            get;
            set;
        }

        /// <summary>Gets all articles that do not reference another article and match the criteria defined by
        /// <paramref name="filter"/>.</summary>
        /// <exception cref="InvalidOperationException"><see cref="Cache.Dispose"/> has been called on the parent
        /// <see cref="Cache"/> object, or, <see cref="IDeletablePersistentObject.Delete"/> has been called on this or
        /// the parent <see cref="IHost"/> object.</exception>
        IEnumerable<IInboundArticle> GetOriginalInboundArticles(InboundArticleFilter filter);

        /// <summary>Gets the number of articles that do not reference another article and match the criteria defined by
        /// <paramref name="filter"/>.</summary>
        /// <exception cref="InvalidOperationException"><see cref="Cache.Dispose"/> has been called on the parent
        /// <see cref="Cache"/> object, or, <see cref="IDeletablePersistentObject.Delete"/> has been called on this or
        /// the parent <see cref="IHost"/> object.</exception>
        int GetOriginalInboundArticleCount(InboundArticleFilter filter);

        /// <summary>Sets the <see cref="IInboundArticle.HasBeenRead"/> property of all articles of this group to
        /// <c>true</c>.</summary>
        /// <exception cref="InvalidOperationException"><see cref="Cache.Dispose"/> has been called on the parent
        /// <see cref="Cache"/> object, or, <see cref="IDeletablePersistentObject.Delete"/> has been called on this or
        /// the parent <see cref="IHost"/> object.</exception>
        /// <remarks><strong>Note</strong>: After calling this method, the next call to <see cref="Cache.SaveChanges"/>
        /// on the parent <see cref="Cache"/> object will return <c>true</c>.</remarks>
        void MarkAllInboundArticlesAsRead();
    }
}
